.\"
.\" Copyright (C) 1994-2021 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of both the OpenPBS software ("OpenPBS")
.\" and the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" OpenPBS is free software. You can redistribute it and/or modify it under
.\" the terms of the GNU Affero General Public License as published by the
.\" Free Software Foundation, either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" OpenPBS is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" PBS Pro is commercially licensed software that shares a common core with
.\" the OpenPBS software.  For a copy of the commercial license terms and
.\" conditions, go to: (http://www.pbspro.com/agreement.html) or contact the
.\" Altair Legal Department.
.\"
.\" Altair's dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of OpenPBS and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair's trademarks, including but not limited to "PBS™",
.\" "OpenPBS®", "PBS Professional®", and "PBS Pro™" and Altair's logos is
.\" subject to Altair's trademark licensing policies.
.\"
.TH pbs_sched_attributes 7B "4 March 2020" Local "PBS Professional"
.SH NAME
.B pbs_sched_attributes
\- attributes of default PBS scheduler and multischeds
.SH DESCRIPTION
These are the attributes of the default PBS scheduler and PBS multischeds.

.IP comment 8
For certain scheduler errors, PBS sets the scheduler's 
.I comment
attribute to specific error messages.  You can use the 
.I comment 
attribute to notify another administrator of something, but PBS does overwrite
the value of 
.I comment 
under certain circumstances.
.br
Readable by all; settable by Manager.
.br
Format: 
.I String
.br
Default: no default
.br
Python type: No Python type

.IP do_not_span_psets 8
Specifies whether or not the scheduler requires the job to fit within
one existing placement set.
.br
Readable by all; settable by Manager and Operator.
.br
Format: 
.I Boolean
.br
Behavior:
.nf
   True   The job must fit in one existing placement set.  All 
          existing placement sets are checked.  If the job fits 
          in an occupied placement set, the job waits for the 
          placement set to be available.  If the job cannot fit 
          within a single placement set, it won't run.
   False  The scheduler first attempts to place the job in a 
          single placement set, but if it cannot, it allows the 
          job to span placement sets, running on whichever
          vnodes can satisfy the job's resource request.
.fi
Default: 
.I False
.br
Python type: No Python type

.IP job_sort_formula_threshold 8
Lower bound for calculated priority for job.  If job priority is at 
or below this value, the job is not eligible to run in the current
scheduler cycle.  
.br
Readable by all; settable by Manager.  
.br
Format: 
.I Float
.br
Default: None
.br
Python type: No Python type

.IP log_events 8
Types of events logged by this scheduler.
.br
Readable by all; settable by Manager and Operator.
.br
Format:
.I Integer
.br
Default:
.I 767
.br
Python type: No Python type

.IP only_explicit_psets 8
Specifies whether placement sets are created for unset resources.  
.br
Readable by all; settable by Manager and Operator.
.br
Format: 
.I Boolean
.br
Behavior:
.nf
   True   Placement sets are not created from vnodes 
          whose value for a resource is unset.
   False  placement sets are created from vnodes whose 
          value for a resource is unset.
.fi
Default:
.I False
.br
Python type: No Python type

.IP opt_backfill_fuzzy 8
Sets the tradeoff between scheduling cycle speed and granularity of 
estimated start time calculation.  
.br
Readable by all; settable by Manager.
.br
Behavior: 
.RS 11
.IP off 8
Finest granularity; no speedup.
.IP low 8
Fairly fine granularity; some speedup.
.IP medium 8
Medium granularity; medium speedup.
.IP high 8
Coarse granularity; greatest speedup.
.RE
.IP
.br
Format: 
.I String
.br 
Default: unset (behaves like 
.I low
).
.br
Python type: No Python type

.IP partition 8
Name of partition for which this scheduler is to run jobs.
Cannot be set on default scheduler.
.br
Format:
.I String
.br
Default: "None"
.br
Python type: No Python type

.IP pbs_version 8
The version of PBS for this scheduler.  
.br
Readable by Manager and Operator; not settable.
.br
Format:
.I String
.br
Default: no default
.br
Python type: No Python type

.IP preempt_order
Defines the order of preemption methods which this scheduler uses on
jobs. This order can change depending on the percentage of time
remaining on the job. The ordering can be any combination of 
.I S, C, R, 
and 
.I D.  

Usage: an ordering 
.I (SCR) 
optionally followed by a percentage of time remaining and another
ordering.

For example, PBS should first attempt to use suspension to preempt a
job, and if that is unsuccessful, requeue the job: 
.nf
   preempt_order: "SR"
.fi

For example, if the job has between 100% and 810f requested time
remaining, first try to suspend the job, then try checkpoint, then
requeue. If the job has between 80% and 510f requested time
remaining, attempt suspend, then checkpoint.  Between 50% and 0% time
remaining, just attempt to suspend the job:
.nf
   preempt_order: "SCR 80 SC 50 S"
.fi

For each job percentage, each method can be used only once.  Note that
in the example above, the 
.I S 
method appears only once per percentage. 

Readable by all; settable by Manager.
.br
Format:
.I String, 
as a quoted list
.br
Preemption methods:
.nf
   C   Checkpoint job
   D   Delete job
   R   Requeue job
   S   Suspend job
.fi
Default: 
.I "SCR"
.br
Python type: No Python type

.IP "preempt_prio" 8
Specifies the ordering of priority for different preemption levels.
Two or more job types may be combined at the same priority level with
a plus sign ("+") between them, using no whitespace.  Comma-separated
preemption levels are evaluated left to right, with higher priority to
the left.  Any level not specified in the
.I preempt_prio 
list is ignored.  

For example, starving jobs have the highest priority, then normal
jobs, and jobs whose entities are over their fairshare limit are third
highest:
.nf
   preempt_prio: "starving_jobs, normal_jobs, fairshare"
.fi

For example, starving jobs whose entities are also over their
fairshare limit are lower priority than normal jobs: 
.nf 
   preempt_prio: "normal_jobs, starving_jobs+fairshare"
.fi

Readable by all; settable by Manager.
.br
Format:
.I string_array,
as quoted string
.br
Preemption levels:
.nf
   express_queue      Jobs in express queues preempt other jobs.  
.fi
.RS 30
See 
.I preempt_queue_prio.  
Does not require 
.I by_queue 
to be 
.I True. 
.RE
.RS 8
.nf
   starving_jobs      When a job becomes starving it can preempt 
                      other jobs.  
   fairshare          When the entity owning a job exceeds its 
                      fairshare limit.       
   queue_softlimits   Jobs which are over their queue soft limits     
   server_softlimits  Jobs which are over their server soft limits    
   normal_jobs        The preemption level into which a job falls 
                      if it does not fit into any other specified 
                      level.     
.fi

Default:
.I "express queue, normal_jobs"
.br
Python type: No Python type
.RE

.IP preempt_queue_prio 8
Specifies the minimum queue priority required for a queue to be
classified as an express queue.  Express queues do not require
.I by_queue 
to be 
.I True.
.br
Readable by all; settable by Manager.
.br
Format:
.I Integer
.br
Default:
.I 150
.br
Python type: No Python type

.IP preempt_sort 8
Specifies whether jobs most eligible for preemption are sorted
according to their start times.  
.br
Readable by all; settable by Manager.
.br
Format:
.I String
.br
Behavior:
.nf
   unset                 Preempted job will be that with 
                         longest running time.
   min_time_since_start  First job preempted will be that with 
                         most recent start time.
.fi
.br
Default:
.I min_time_since_start
.br
Python type: No Python type

.IP scheduler_iteration 8
Time in seconds between scheduling iterations.  If you set the
server's 
.I scheduler_iteration 
attribute, that value is assigned to the default scheduler's 
.I scheduler_iteration
attribute, and vice versa.
.br
Readable by all; settable by Manager.
.br
Format:
.I Integer
.br
Units:
Seconds
.br
Default:
.I 600
.br
Python type: No Python type

.IP scheduling 8
Enables scheduling of jobs.  
.br
If you set the server's 
.I scheduling 
attribute, that value is
assigned to the default scheduler's 
.I scheduling 
attribute, and
vice versa.
.br
Readable by all; settable by Manager.
.br
Format:
.I Boolean
.br
Default value for default scheduler:
.I True
.br
Default value for multischeds: 
.I False
.br
Python type: No Python type

.IP sched_cycle_length 8
The scheduler's maximum cycle length.  
Overwritten by the 
.I -a
option to the
.I pbs_sched
command.
.br
Readable by all and settable by the PBS Manager and Operator only.
.br
Format: 
.I Duration
 expressed as integer seconds, or 
.I [[hours:]minutes:]seconds[.milliseconds]
.br
Default: 
.I 20:00 (20 minutes)
.br
Python type: No Python type

.IP sched_host 8
The hostname of the machine on which this scheduler runs.  
.br
Cannot be set on default scheduler; value for default scheduler is server
hostname.  
.br
Must be set by administrator.
.br
Readable by Manager and Operator.
.br
Format: 
.I String
.br
Default value for multischeds: server hostname
.br
Python type: No Python type

.IP sched_log 8
Directory where this scheduler writes its logs.  Permissions should be
755.  Must be owned by root.  Cannot be shared with another scheduler.
.br
Format: 
.I String
.br
Default: 
.I $PBS_HOME/sched_logs_<scheduler name>

.IP sched_port 8
.B Removed. 

.IP sched_preempt_enforce_resumption 8
Controls whether the scheduler treats preempted jobs as top jobs.  
.br
When 
.I True
, preempted jobs are treated as top jobs.  
.br
Readable by all; settable by Manager.
.br 
Format: 
.I Boolean
.br
Default: 
.I False
.br
Python type: No Python type

.IP sched_priv 8
Directory where this scheduler keeps its fairshare usage, resource_group, 
holidays, and sched_config files. Must be owned by root.  
For default scheduler, use default value; do not set.  Settable for 
multischeds.
.br
Readable by all; settable by Manager (for multischeds).
.br
Format: 
.I String
.br
Default: 
.I $PBS_HOME/sched_priv_<scheduler name>
.br
Python type: No Python type


.IP state 8
State of this scheduler. 
.br
States:
.RS 11
.IP down
Scheduler is not running.
.IP idle
Scheduler is running and is waiting for a scheduling cycle to be triggered.
.IP scheduling
Scheduler is running and is in a scheduling cycle.
.RE
.IP 
Format:
.I String
.br
Default value for default scheduler: 
.I idle
.br
Default value for multischeds:
.I down
.br
Python type: No Python type

.IP throughput_mode  8
Allows scheduler to run faster; it doesn't have to wait for each job
to be accepted, and doesn't wait for 
.I execjob_begin 
hooks to finish.  Also allows jobs that were changed via 
.I qalter, server_dyn_res 
scripts, or peering to run in the same scheduling cycle where they
were changed.
.br
Readable by all; settable by Manager and Operator.
.br
Format: 
.I Boolean
.br
Behavior:
.nf
   True    Scheduler runs asynchronously and faster.  Only available 
           when PBS complex is in TPP mode.
   False   Scheduler does not run asynchronously
.fi
.br
Default: 
.I True
.br
Python type: No Python type


.SH SEE ALSO
.B qmgr(1B)
